.\" Copyright 2008-2010 Vadim Zhukov <persgray@gmail.com>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright notice,
.\"    this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright notice,
.\"    this list of conditions and the following disclaimer in the documentation
.\"    and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY AGAVA COMPANY ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
.\" EVENT SHALL THE AGAVA COMPANY OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" The views and conclusions contained in the software and documentation are
.\" those of the authors and should not be interpreted as representing official
.\" policies, either expressed or implied, of the AGAVA Company.
.Dd $Mdocdate$
.Dt RB 5 URM
.Os AGAVA
.Sh NAME
.Nm rb
.Nd RB profile and archive information files
.Sh DESCRIPTION
The
.Xr rb 7
utlities set all use the same configuration files called profiles.
Layout of those files is described below in .
Also, each archive is accompanied with similar-named file, which
has
.Dq .info
extension.
Those files contains information how and when archive was created, which is
needed for correct manipulating archives even if profile changed.
For example, you change file archives format from
.Dv tar
to
.Dv cpio ,
so all dumps that'll happen will now create cpio archives.
But old tar archives are still there and usable, and will be rotated together
with new archives.
Archive information files are simple, so we discuss them now, and all the rest
of this manual will be related to profiles.
.Sh ARCHIVE INFORMATION FILES
Each archive information file (AIF) consists of text lines that looks like
INI-file directives: field name, equal sign
.Dq \&=
and field value.
Currently there are 5 fields used:
.Bl -ohang
.It Va begin
Timestamp when archive dumping began.
Field value has following format: %Y-%m-%d %H:%M:%S (see
.Xr strftime 3
for description).
Note, that there could be more than one
.Va begin
line if item was re-dumped (in case of error, for example).
.It Va end
Similar to
.Va begin ,
it is timestamp when archive dumping ended.
.It Va compressed
Possible values:
.Dq yes ,
.Dq no .
Indicates if archive was compressed.
Compressed archives usually have
.Dq .gz
suffix added to extension.
Unlike
.Va Va compress
profile module option, it's just a boolean flag.
We don't need to know level of compression, so don't bother ourselves with it.
.It Va exit_code
Exit code of remote agent.
Zero means dump ended OK, non-zero indicates error.
.It Va extension
Extension given to archive, including all suffixes like
.Dq .gz .
.It Va format
Data may be represented in many formats.
For example, PostgreSQL database could be dumped in any of three formats.
So we save this infromation too. See also description of
.Va archive_format
profile mode option below.
.It Va increment_from
Marks this archive as increment.
Value is date of master archive in YYYYMMDD format.
.It Va type
Says what type of data is there: file(-s), database etc. See also description of
.Va Va what
profile module option below.
.It Va preferred_date
Says which date to take full dump on is preferred.
Such values are meaningful only when using incremental dumps.
Can be specified in any following form:
.Bl -tag -width "day number" -offset indent
.It weekday
Weekday name, short or long, ignoring case: Saturday, mOn.
In month day context means first such week day in month.
.It day number
In weekday context it can be any number in range 0..6, where 0 means Sunday.
Otherwise (in month day context) it can be any positive integer.
.It Dq hash
Calculates (internally) a hash for each combination of host and module name.
This hash is then connected to day when full dump should be started.
It is guaranteed that same versions of
.Nm
will generate same hashes for same host and module names, ignoring case.
.It .Dq round-robin
An actual value will be shifted (with rotating if needed) for each
host being served.
This can help to reduce the load caused by making all full dumps at the same
day.
.El
.El
.Sh PROFILE STRUCTURE
Profile looks like similar to INI-files.
It is divided in sections, and each section has name in square brackets and
pairs
.Dq name \&= value ,
one per line.
Lines can be combined by backslash
.Sq \e
at the end of line.
.Pp
Comments are denoted by hash mark
.Sq # .
Comments start from a newline (possibly with some whitespace between line
start and the comment) and continue till the end of line.
Comments are subjects to line conecatenation via backslash unlike
.Xr sh 1 ,
for example.
.Pp
Each profile should have at least two sectons. One section should be called
.Dq global .
It consists of parameters that define the whole backup (view, restore) process.
All other sections specify items to backup.
Each such section represents a so-called backup module.
.Dq [global]
section can be also called
.Dq global module .
.Pp
Section names are case-insensetive.
Internally, section names are converted to lowercase.
Section names should be unique across profile.
Sections cannot be split, i.e., following is not allowed:
.Bd -literal -offset indent
[section_1]
\&...
[section_2]
\&...
[section_1]
\&...
.Ed
.Sh PROFILE OPTIONS
Each option consists of name and value, delimited by
.Dq \&=
sign.
Names are case-insensetive and converted to lowercase internally, as with
section names. Options accept different types of values, some options ever
accept more than one type. Values for some option types are case-sensitive and
some are not, this is mentioned in each option's description below.
.Bl -ohang
.It Vt boolean
Case-insensetive.
Can be in
.Dq enabled
or
.Dq disabled
state.
Accepts
.Dq yes ,
.Dq true ,
.Dq on
as
.Dq enabled
synonims;
.Dq no ,
.Dq false
and
.Dq off
as
.Dq disabled
synonims.
.It Vt compresslevel
A decimal digit.
.Dq 0
means
.Dq disabled ,
any other specifies compression level, see
.Xr gzip 1 .
.It Vt count
A non-negative decimal number.
.It Vt enumeration
A set of values, one (and only one) of which should be selected.
.It Vt size
Case-sensitive.
A non-negative decimal number with optional
.Dq B ,
.Dq K ,
.Dq M ,
.Dq G ,
.Dq T ,
.Dq P
or
.Dq E
suffix, which stand for bytes, kilobytes, megabytes, gigabytes, terabytes,
petabytes and exabytes, respectively.
Missing suffix means bytes.
.Em NOTE :
Perl, on which
.Xr rb 7
is based, do not handle well a really big numbers.
.Xr Math::BigInt 3p
Perl module helps a bit, but tools are not bignum-safe now.
.It Vt percent
A decimal number in range 0\(en100 with
.Dq %
sign as suffix.
.It Vt port
A TCP/UDP port, decimal number in range 1\(en65535.
.It Vt rotaterules
A string in a form
.Sm off
.Do
.Cm X Li m
.Cm Y Li w
.Cm Z Li d
.Dc
.Sm on
where
.Cm X , Y
and
.Cm Z
represent number of month, week and day backups kept, respectively.
For description what are month, week and day backups, see
.Xr rb 7 .
.It Vt string
Accepts a plain text string, which is subject to shell-like word splitting.
Quoting is supported.
.It Vt time
A string in a form
.Sm off
.Do
.Cm X Li h
.Cm Y Li m
.Cm Z Li s
.Dc
.Sm on
where
.Cm X , Y
and
.Cm Z
represent hours, minutes and seconds.
You can now use values like
.Dq 90m
or
.Dq 3h1m416s ,
if you like, but this behavior may be changed later, so do not depend on this
feature.
.El
.Sh GLOBAL PROFILE OPTIONS
Following options should appear only in
.Cm [global]
section.
Options are listed with their types default values (if any) and list of programs
operations those options are involved into.
.Bl -ohang
.It Va abort_if_exist ( Vt boolean )
Default value:
.Dv yes
.br
Used when: dumping
.br
Abort backing up any item from host if it was already backed up at the date
specified.
.It Va abort_if_free ( Vt percent , size )
Default value: none
.br
Used when: dumping
.br
Abort backing up if ammount of destination file system free space is lower than
specified. Ignored in test mode. Not supported yet.
.It Va autorotate ( Vt boolean )
Default value:
.Dv enabled
.br
Used when: dumping
.br
Automatically call rotate program after host dump.
This is better than
.Dq rb_dump; rb_rotate
because rotating will be started in background, while proceeding next host dump.
.It Va archive_dir ( Vt string )
Default value:
.Dv ~/dumps
.br
Used when: dumping, listing, putting, restoring, rotating
.br
Directory where to save archives.
Each backed up host is represented by a subdirectory here, and each backup
module is represented by a subdirectory in host directory. Also, here is located
main log file
.Pa rb.log .
.It Va max_retry_count ( Vt count )
Default value: 30
.br
Used when: dumping, putting, restoring
.br
Each network operation will be retried on error not more than
.Va max_retry_count
times.
Such operations are, for example, dumping data or updating an agent.
.It Va min_remote_time ( Vt time )
Default value:
.Dv 0
.br
Used when: dumping, putting, restoring
.br
Minimum time to spend between making connections to remote host.
Helps to avoid blocking by firewall due to many connections in a small time
period.
.Pp
.Em NOTE :
You can now use values like
.Dq 90m
or
.Dq 3h1m416s ,
if you like, but this may be changed later, so do not depend on this feature.
.It Va retry_wait ( Vt time )
Default value:
.Dv 60
.br
Used when: dumping, putting, restoring
.br
Wait time between each retry to back up in case backup process failed.
If
.Va min_remote_time
is set then the largest from
.Va min_remote_time
and
.Va retry_wait
will be used.
.It Va ssh_identity ( Vt string )
Default value: none (use SSH defaults)
.br
Used for: dumping, putting, restoring
.br
Secret key to use for authentification when connecting to host being backed up
via SSH.
See description of
.Fl i
flag in
.Xr ssh 1 .
.It Va ssh_port ( Vt port )
Default value: none (use SSH defaults)
.br
Used for: dumping, putting, restoring
.br
TCP port to use when connecting to host being backed up via SSH.
See description of
.Fl p
flag in
.Xr ssh 1 .
.It Va ssh_user ( Vt string )
Default value: none (use SSH defaults)
.br
Used for: dumping, putting, restoring
.br
Username to use when connecting to host being backed up via SSH.
See description of
.Fl l
flag in
.Xr ssh 1 .
.El
.Sh MODULE OPTIONS
Following options should appear only in sections that describe backup modules.
Not all options are related to all kinds of archived data, this information.
.Bl -ohang
.It Va archive_format ( Vt enumeration )
Default value:
.Dv cpio
for files,
.Dv plain
for MySQL,
.Dv tar
for postgres
.br
Possible values:
.Dv cpio
and
.Dv tar
for
.Dv files ;
.Dv plain
for
.Dv mysql ;
.Dv native ,
.Dv plain
and
.Dv tar
for
.Dq postgres
.br
Used when: dumping, restoring
.br
Module types: all
.br
Affects archive extension
.br
Type of archive to create. Note that different archive formats may be not
absolutely equal in terms of information saved.
.It Va compress ( Vt boolean , Vt compresslevel )
Default value:
.Dv disabled
.br
Used when: dumping, restoring
.br
Module types: all
.br
Enables or disables compression of archives via
.Xr gzip 1 .
Compression is done on the remote host.
Compressed archives will have
.Dq .gz
added to their extension.
.It Va incremental_daily ( Vt boolean )
Default value:
.Dv disabled
.br
Used when: dumping, listing, restoring, rotating
.br
Module types: files
.br
Enables incremental dumping for daily backups.
These backups will have last incremental weekly or full (what is younger) backup
as master.
.It Va incremental_weekly ( Vt boolean )
Default value:
.Dv disabled
.br
Used when: dumping, listing, restoring, rotating
.br
Module types: files
.br
Enables incremental dumping for weekly backups.
These backups will have last full backup as master.
.It Va max_retry_count ( Vt count )
Default value: same as in
.Dq global
section.
.br
Used when: dumping, putting, restoring
.br
Module types: all
.br
See description in
.Sx GLOBAL OPTIONS
above.
.It Va monthly_dump_at ( Vt preferred_date )
Default value: 1
.br
Used when: dumping
.br
Module types: files
.br
Defines day of month when taking full dump is preferred.
Used only when incremental_montly is enabled.
Can be specified in two formats: either by just month day number (starting from
1) or
.Dq Op Va weekday week Op Va weeknumber .
In the latter case, 
.Va weeknumber
is count from first month day, starting from 1.
.Pp
If month day or week number is greater than quantity of days or weeks,
respectively, then maximum possible values is used.
This can be used, for example, to force taking dumps at last day of month.
.It Va rotate ( Vt rotaterules )
Default value:
.Dv 1m1w1d
.br
Used when: rotating
.br
Module types: all
.br
Rotating archives scheme.
For a detailed description of it, see
.Xr rb 7 .
.It Va separate_archives ( Vt boolean )
Default value:
.Dv disabled
.br
Used when: dumping, putting, restoring, rotating
.br
Module types: all
.br
Put each item into it's own archive.
.Pp
When putting archives with
.Va separate_archives
set, there are some corener cases: if item is a directory, then archive will be
put in this directory; otherwise, archive will be put in item's parent
directory.
For multi-level
.Dq files
items, corresponding subdirectory hierarchy will be created:
For example, the following configuration:
.Bd -literal -offset indent
[webdocs]
what              = files
which             = www/htdocs
workdir           = /var
.Ed
.Pp
will force
.Pa webdocs/www/htdocs
subdirectory hierarchy in host's directory to be created.
Please note that for multi-level items this is not the same as working
directory (specified by
.Va workdir
option).
.It Va socket ( Vt string )
Default value: none (use defaults)
.br
Used when: dumping, restoring
.br
Module types: mysql
.br
Path to (MySQL) socket on the host dumping from or restoring to.
.It Va what ( Vt enumeration )
Default value: none; option is mandatory
.br
Possible values: files, mysql, postgres
.br
Used when: dumping, restoring
.br
Module types: any
.br
Affects archive extension
.br
Select a dump source: file hierarchies or databases.
More types are planned to support in the future.
.It Va which ( Vt string )
Default value: none; option is mandatory
.br
Used when: dumping, putting, restoring
.br
Module types: any
.br
Describes which items (files, directories, databases...) to archive.
.Pp
For
.Dq Li what \&= files
case, item names will go through shell expansion within working directory.
.Pp
For
.Dq Li what \&= mysql
and
.Dq Li what \&= postgres
cases,
.Sq *
means just
.Dq all databases .
You can specify some database names explicitly before and/or after
.Sq * ,
to make sure they will be backed up before and/or after all other.
Doing such thing with system databases (such as
.Dq mysql
in MySQL) definitely is a good idea.
.Pp
.Em NOTE :
there are no checks for items now, so make sure items list could not be affected
by any untrusted third party.
.It Va workdir ( Vt string )
Default value: none (not changed after connecting)
.br
Used when: dumping, putting, restoring
.br
Module types: files
.br
Dumping/extracting will be done from/to this directory on a remote host.
Putting will result archive will be put in this directory on a remote host (but
see
.Dq separate_archives
option description).
.El
.Sh FILES
.Bl -tag -width "~/.rb/cpanel"
.It Pa ~/.rb/cpanel
Sample config file, for cPanel-based hosting.
.El
.Sh SEE ALSO
.Xr pax 1 ,
.Xr ssh 1 ,
.Xr rb 7
.Sh AUTHORS
The
.Nm
manual page was written by
.An Vadim Zhukov Aq persgray@gmail.com .
.Sh HISTORY
The
.Nm
profile format was introduced in RB 2.0.
.Pp
The
.Nm
archive information file format was introduced in RB 1.0 and was heavily
extended in RB 2.x.
